.\"
.\" Copyright (c) 2001-2020 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd NOVEMBER 26, 2001
.Dt AG_INTRO 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.3
.Sh NAME
.Nm AG_Intro
.Nd agar introduction
.Sh DESCRIPTION
Agar is a general-purpose graphical application toolkit.
It provides all types of applications (possibly written in different languages)
with consistent interfaces across a multiple platforms.
.Pp
.Sh AGAR-CORE
Agar's non-graphical core and utility library is
.Em ag_core .
It implements the base
.Xr AG_Object 3
system,
.Xr AG_Event 3
mechanism and
.Xr AG_Timers 3 .
It also provides cross-platform interfaces to operating system services
such as kernel-based events, timers, threads and filesystems.
.Pp
To use this library (without GUI) link against
.Sq agar-core-config --libs
.Pp
.\" SYNC WITH AG_Core(3) "SEE ALSO"
.Bl -tag -width "AG_DataSource(3) " -compact
.It Xr AG_Config 3
Manage Agar configuration settings.
.It Xr AG_Core 3
Core Agar library initialization.
.It Xr AG_DataSource 3
Generic interface to different data sources.
.It Xr AG_Db 3
Database access methods.
.It Xr AG_DSO 3
Cross-platform interface to dynamic linkers.
.It Xr AG_Error 3
Error handling in Agar.
.It Xr AG_Event 3
Virtual functions (at the Agar object level).
.It Xr AG_EventLoop 3
Main application event loop.
General event sources and sinks.
.It Xr AG_Execute 3
Cross-platform interface to program execution.
.It Xr AG_File 3
Portable interface to filesystems.
.It Xr AG_Limits 3
Interface to platform-dependent limits.
.It Xr AG_Object 3
The Agar object system.
.It Xr AG_String 3
Functions for manipulating C strings.
.It Xr AG_TextElement 3
Multilanguage dynamic text buffer.
.It Xr AG_Threads 3
Portable threads interface.
.It Xr AG_Timer 3
Timer facility.
.It Xr AG_Time 3
Interface to time sources.
.It Xr AG_User 3
Cross-platform interface to user accounts.
.It Xr AG_Variable 3
Primitive data variables and bindings.
.It Xr AG_Version 3
Datafile versioning.
.El
.Sh AGAR-GUI: BASE SYSTEM
The
.Em ag_gui
library is the Agar GUI system and standard widget library.
.Pp
To use this library (and
.Em ag_core ) ,
link against
.Sq agar-config --libs
.Pp
.Bl -tag -width "AG_WidgetPrimitives(3) " -compact
.It Xr AG_AlphaFn 3
Alpha blending functions.
.It Xr AG_Color 3
Color structure.
.It Xr AG_Cursor 3
Cursor configuration.
.It Xr AG_Driver 3
Driver (backend) interface.
.It Xr AG_GlobalKeys 3
Application-wide keyboard shortcuts.
.It Xr AG_GL 3
OpenGL-specific functions.
.It Xr AG_GuiDebugger 3
GUI debugging tool.
.It Xr AG_KeySym 3
Keyboard key definitions.
.It Xr AG_KeyMod 3
Keyboard modifier definitions.
.It Xr AG_MouseButton 3
Mouse button definitions.
.It Xr AG_StyleSheet 3
Agar's version of cascading style sheets.
.It Xr AG_Surface 3
Graphics surfaces.
.It Xr AG_Text 3
Typography; interface to the font engine.
.It Xr AG_Units 3
Conversion between different unit systems.
.It Xr AG_Widget 3
The base class for Agar widgets (and windows).
.It Xr AG_WidgetPrimitives 3
Rendering primitives for GUI elements.
.It Xr AG_Window 3
The base container for Agar widgets.
.El
.Sh AGAR-GUI: STANDARD WIDGETS
Standard widgets included in
.Em ag_gui
(unless "--disable-widgets" is used).
.Pp
.Bl -tag -width "AG_ObjectSelector(3) " -compact
.It Xr AG_Box 3
Horizontal/vertical widget container.
.It Xr AG_Button 3
Push-button widget.
.It Xr AG_Checkbox 3
Checkbox widget.
.It Xr AG_Combo 3
Canned text input/drop-down menu widget.
.It Xr AG_Console 3
Scrollable text console widget.
.It Xr AG_DirDlg 3
Directory selection widget.
.It Xr AG_Editable 3
The Agar text editor (plain editable field).
.It Xr AG_FileDlg 3
File selection widget.
.It Xr AG_Fixed 3
Container for fixed position/geometry widgets.
.It Xr AG_FontSelector 3
Font selection widget.
.It Xr AG_GLView 3
Low-level OpenGL context widget.
.It Xr AG_Graph 3
Graph display widget.
.It Xr AG_FixedPlotter 3
Plotter for integral values.
.It Xr AG_HSVPal 3
Hue/saturation/value color picker widget.
.It Xr AG_Icon 3
Drag-and-droppable object that can be inserted into
.Xr AG_Socket 3
widgets.
.It Xr AG_Label 3
Display a string of text (static or polled).
.It Xr AG_MPane 3
Standard single, dual, triple and quad paned view.
.It Xr AG_Menu 3
Menu widget.
.It Xr AG_Notebook 3
Notebook widget.
.It Xr AG_Numerical 3
Spinbutton widget (for integers or floats).
.\" .It Xr AG_ObjectSelector 3
.\" Selector for
.\" .Xr AG_Object 3
.\" trees.
.It Xr AG_Pane 3
Dual paned view.
.It Xr AG_Pixmap 3
Displays arbitrary surfaces.
.It Xr AG_ProgressBar 3
Progress bar widget.
.It Xr AG_Radio 3
Simple radio group widget (integer).
.It Xr AG_Scrollbar 3
Scrollbar (integer or floating-point).
.It Xr AG_Scrollview 3
Scrollable view.
.It Xr AG_Separator 3
Cosmetic separator widget.
.It Xr AG_Slider 3
Slider control (integer or floating-point).
.It Xr AG_Socket 3
Placeholder for drag-and-droppable
.Xr AG_Icon 3 .
.It Xr AG_Statusbar 3
Specialized statusbar widget.
.It Xr AG_Table 3
Table display widget.
.It Xr AG_Treetbl 3
Tree-based table display widget.
.It Xr AG_Textbox 3
The Agar text editor (an
.Ft AG_Editable
in a box).
.It Xr AG_Tlist 3
Linearized tree / list box widget.
.It Xr AG_Toolbar 3
Specialized button container for toolbars.
.It Xr AG_UCombo 3
Single-button variant of
.Xr AG_Combo 3 .
.El
.Sh AGAR-MATH
.Em ag_math
is a general-purpose, performance-oriented math library which extends
.Em ag_gui
with new widgets and support for linear-algebra types.
.Pp
To use this library, link against
.Sq agar-math-config --libs .
.Pp
.Bl -tag -width "M_Quaternion(3) " -compact
.It Xr M_Matrix 3
Matrix operations.
Provides optimized methods for sparse matrices
(common in scientific applications)
as well as 4x4 matrices
(common in computer graphics).
.It Xr M_Circle 3
Circles in R^2 and R^3.
.It Xr M_Color 3
Mapping between different color spaces.
.It Xr M_Complex 3
Complex-number arithmetic (w/o compiler extensions).
.It Xr M_Coordinates 3
Mapping between different coordinate systems.
.It Xr M_Sort 3
Sort algorithms (qsort, heapsort, mergesort, radixsort)
.It Xr M_IntVector 3
Vector operations for vectors with integer elements.
.It Xr M_String 3
Math-specific extensions to the
.Xr AG_Printf 3
engine.
.It Xr M_Line 3
Lines, half-lines and line segments.
.It Xr M_Matview 3
Visualization widget for
.Xr M_Matrix 3 .
.It Xr M_Plane 3
Routines related to planes in R^3.
.It Xr M_Plotter 3
General-purpose plotting widget (displays sets of
.Ft M_Real ,
.Ft M_Vector
and
.Ft M_Complex
elements).
.It Xr M_PointSet 3
Operations on sets of points (e.g., convex hulls).
.It Xr M_Polygon 3
Operations related to polygons in R^2 and R^3.
.It Xr M_Quaternion 3
Basic quaternion arithmetic.
.It Xr M_Rectangle 3
Routines specific to rectangles in R^2 and R^3.
.It Xr M_Triangle 3
Routines specific to triangles in R^2 and R^3.
.It Xr M_Vector 3
Vectors (optimized R^2, R^3 and R^4 or general R^n).
.El
.Sh AGAR-NET
.Em ag_net
provides network access and HTTP application server functionality.
.Pp
To use this library, link against
.Sq agar-net-config --libs .
.Pp
.Bl -tag -width "AG_Net (3) " -compact
.It Xr AG_Net 3
Interface to network services.
.It Xr AG_Web 3
HTTP/1.1 application server.
.El
.Sh AGAR-SG
(Beta)
.Em ag_sg
implements 3D scene-graph, rendering and geometry methods.
.Pp
To use this library, link against
.Sq agar-sg-config --libs
.Pp
.Bl -tag -width "SG_CgProgram(3) " -compact
.It Xr SG 3
Base scene graph object.
.It Xr SG_Image 3
Textured polygon generated from an image surface.
.It Xr SG_Camera 3
Viewpoint in scene (tied to the
.Xr SG_View 3
widget).
.It Xr SG_CgProgram 3
Vertex/fragment program in the Cg language.
.It Xr SG_Circle 3
Circle (reference geometry).
.It Xr SG_Geom 3
Base class for reference geometry objects.
.It Xr SG_Light 3
Light source.
.It Xr SG_Node 3
Base class for all elements of a
.Xr SG 3
scene.
.It Xr SG_Object 3
Base class for polyhedral objects (as brep).
.It Xr SG_Plane 3
Plane (reference geometry).
.It Xr SG_Point 3
Single point (reference geometry).
.It Xr SG_Polygon 3
Polygon (reference geometry).
.It Xr SG_PolyBall 3
Sphere (as polyhedral approximation).
.It Xr SG_PolyBox 3
Rectangular box (as polyhedron).
.It Xr SG_Program 3
Base class for vertex or fragment programs.
.It Xr SG_Rectangle 3
Rectangle (reference geometry).
.It Xr SG_Sphere 3
Sphere (reference geometry).
.It Xr SG_Texture 3
Texture compiled from a set of surfaces.
.It Xr SG_Triangle 3
Triangle (reference geometry).
.It Xr SG_View 3
Agar visualization and editor widget for
.Xr SG 3
scenes.
.It Xr SG_Voxel 3
Voxel object.
.El
.Sh AGAR-SK
(Beta)
.Em ag_sk
implements dimensioned 2D sketches with constraint solving.
Sketches can contain sets of metric relations (i.e., distances, angles)
and logical relations (i.e., coincidence, parallelism, tangency), and SK's
attempts to find a solution using degree-of-freedom analysis.
.Pp
To use this library, link against
.Sq agar-sk-config --libs .
.Pp
.Bl -tag -width "SK_View(3) " -compact
.It Xr SK 3
Base sketch object.
.It Xr SK_View 3
Agar visualization widget for sketch objects.
.El
.Sh AGAR-AU
(Beta)
The
.Em ag_au
library is intended to provide a cross-platform sound interface and to
extend
.Em ag_gui
with widgets useful in audio applications.
.Pp
To use this library, link against
.Sq agar-au-config --libs .
.Pp
.Bl -tag -width "AU_DevOut(3) " -compact
.It Xr AU 3
Audio library initialization.
.It Xr AU_Wave 3
Structure containing an audio stream.
.It Xr AU_DevOut 3
Interface to audio output device.
.El
.Sh AGAR-MAP
(Beta) The
.Em ag_map
library implements a simple 2D tile engine.
.Pp
To use this library, link against
.Sq agar-map-config --libs .
.Pp
.Bl -tag -width "RG_Tileview(3) " -compact
.It Xr MAP 3
Base map object.
.It Xr MAP_Actor 3
Map object rendered dynamically.
.It Xr MAP_View 3
Visualization and edition widget.
.It Xr RG 3
Feature-based 2D pixel graphics.
.It Xr RG_Feature 3
Base feature framework.
.It Xr RG_Pixmap 3
A pixmap image element.
.It Xr RG_Sketch 3
A vector sketch element.
.It Xr RG_Texture 3
A texture element.
.It Xr RG_Tile 3
Base tile element.
.It Xr RG_Tileview 3
Edition and visualization widget.
.El
.Sh AGAR-VG
.Em ag_vg
handles visualization and edition of 2D vector drawings.
.Xr VG 3
vector drawings are composed of elements such as lines, polygons, curves,
images or text.
The format is meant to be extended with application-specific elements and
edition tools.
Geometrical placement of elements is determined by linear transformations
using floating-point methods.
.Pp
To use this library, link against
.Sq agar-vg-config --libs .
.Pp
.Bl -tag -width "VG_Polygon(3) " -compact
.It Xr VG 3
Vector drawing object.
.It Xr VG_View 3
Agar widget for visualization and edition of drawings.
.It Xr VG_Arc 3
Arc entity.
.It Xr VG_Circle 3
Circle entity.
.It Xr VG_Line 3
Line entity.
.It Xr VG_Polygon 3
Polygon entity.
.It Xr VG_Text 3
Text entity.
.El
.Sh COMMON MANUAL SECTIONS
Manual pages are provided for most Agar object classes.
Some sections are standard throughout the documentation:
.Bl -tag -width "INHERITANCE HIERARCHY "
.It INHERITANCE HIERARCHY
List of inherited parent classes (see
.Xr AG_Object 3
for details on inheritance).
.It EVENTS
The list of events defined (or raised) by this object (see
.Xr AG_Event 3
for details on events).
.It STRUCTURE DATA
List of public structure members which are safe to access directly.
Multithreaded applications must use
.Xr AG_ObjectLock 3
prior to accessing this data (although in some contexts, such as inside event
handler routines, objects can be presumed locked; see
.Xr AG_Threads 3
for details).
.El
.Sh SEE ALSO
.Pp
.Lk https://libAgar.org/
.Pp
.Lk https://github.com/JulNadeauCA/libagar
.Pp
.Lk https://powerfulAgar.com/
